package com.pactera.jep.service.sys.service;

import java.io.InputStream;
import java.util.Map;

import org.apache.commons.net.ftp.FTPClient;

import com.pactera.jep.core.exception.ServiceException;

/**
 * FTP服务类，提供基础的文件上传、下载以及删除功能
 * 
 * @author ghost
 *
 */
public interface FTPService {

	/**
	 * 将本地文件上传至服务器，成功将会返回此文件在ftp服务器中的名称，否则返回一个null
	 * 
	 * @param localFile
	 *            本地文件完全限定名
	 * @return 远程文件名
	 */
	public String save(String localFile) throws ServiceException;
	
	/**
	 * 将本地文件上传至服务器指定路径并返回此文件在ftp服务器中的名称，否则返回一个null。<br />
	 * 指定的路径存在本地目录中，如果不存在将会创建此目录
	 * 如果targetPath为空，那么将会直接保存在当前目录中
	 * @param targetPath
	 * @param localFile
	 * @return
	 */
	public String save(String targetPath, String localFile) throws ServiceException;
	
	/**
	 * 将本地文件上传至服务器指定目录并保存为指定的文件名
	 * @param targetPath
	 * @param in
	 * @return
	 * @throws ServiceException
	 */
	public boolean save(String targetPath, String targetFile, InputStream in) throws ServiceException;

	/**
	 * 从ftp服务器中将指定文件下载至本地
	 * 
	 * @param remoteFile
	 *            远程文件名
	 * @param localPath
	 *            本地文件完全限定名
	 * @return
	 * @throws Exception
	 */
	public boolean download(String remoteFile, String localPath) throws ServiceException;
	
	
	/**
	 * 从ftp服务器指定目录下载指定文件至本地，如果给定的目录为空，那么将从当前目录下载文件
	 * @param remotePath
	 * @param remoteFile
	 * @param localPath
	 * @return
	 * @throws ServiceException
	 */
	public boolean download(String remotePath, String remoteFile, String localPath) throws ServiceException;

	/**
	 * 删除FTP服务器中的指定文件
	 * 
	 * @param remoteFile
	 *            远程文件名
	 * @return true如果删除成功的话
	 * @throws Exception
	 */
	public boolean remove(String remoteFile) throws ServiceException;
	
	/**
	 * 从FTP服务器指定目录中删除指定文件，如果给定的目录为空，那么将从当前目录删除文件
	 * @param remotePath
	 * @param remoteFile
	 * @return
	 * @throws ServiceException
	 */
	public boolean remove(String remotePath, String remoteFile) throws ServiceException;

	/**
	 * 判断给定的文件是否存在于指定目录中
	 * 
	 * @param fileName
	 *            远程文件名
	 * @param targetPath
	 *            目标路径，为空表示当前路径
	 * @return
	 * @throws ServiceException
	 */
	public boolean fileExists(String fileName, String targetPath) throws ServiceException;
	
	
	/**
	 * 将远程目录中指定文件在服务器上进行复制
	 * @param remotePath
	 * @param remoteFile
	 * @param newFile
	 * @throws ServiceException
	 */
	public void copy(String remotePath, String remoteFile, String newFile) throws ServiceException;
	
	/**
	 * 获取FTP服务器上文件，并以InputStream-FTPClient的形式返回，需要调用者手动关闭InputStream和FTPClient对象。<br />
	 * 可以使用{@link FTPService#closeClientQuietly(FTPClient)}方法来关闭FTPClient对象。
	 * @param remotePath
	 * @param remoteFile
	 * @return
	 * @throws ServiceException
	 */
	public Map<InputStream, FTPClient> getAsStream(String remotePath, String remoteFile) throws ServiceException;
	
	/**
	 * 关闭FTPClient对象
	 * @param ftpClient
	 */
	public void closeClientQuietly(FTPClient ftpClient);
}
